home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / c / rmaxtsk.exe / RMAXTASK.H < prev    next >
C/C++ Source or Header  |  1991-12-10  |  15KB  |  316 lines
  1. /*****************************************************************************
  2.  *                  rmaxtask.h                     *
  3.  *****************************************************************************
  4.  * DESCRIPTION: This file contains data structure definitions and function   *
  5.  *        prototypes for the RMAXTask multitasking package.         *
  6.  *                                         *
  7.  * REVISIONS:     1 JUL 90 - RAC - Original code                     *
  8.  *        10 DEC 91 - RAC - Added kill_task() and changed create_task  *
  9.  *                  to return a pointer to the created task    *
  10.  *                  instead of a status code.             *
  11.  *****************************************************************************/
  12.  
  13. /*****************************************************************************
  14.  *              Data Structure Definitions                 *
  15.  *****************************************************************************/
  16.  
  17. #ifndef _RMAXTASK
  18. #define _RMAXTASK
  19.  
  20. #define TDESC    struct task_descriptor
  21.  
  22. TDESC {                    /* The Task Descriptor */
  23.     char    task_name[20];        /* Text task name for debugging */
  24.     TDESC    *prev_wait;        /* Links to other tasks waiting at a */
  25.     TDESC    *next_wait;        /*  mailbox or semaphore */
  26.     TDESC    *prev_time;        /* Links to other tasks waiting on */
  27.     TDESC    *next_time;        /*  the timer */
  28.     long    timeout;        /* Timer expiration time */
  29.     unsigned    priority;        /* 0 = lowest, 0xFFFF = highest */
  30.     char    *stack_bottom;        /* Beginning of memory for stack */
  31.     char    far *my_stack;        /* Far pointer to this task's stack */
  32.     unsigned    my_BP;            /* Saved BP register */
  33.     unsigned    my_SI;            /* Saved SI register */
  34.     unsigned    my_DI;            /* Saved DI register */
  35.     unsigned    wait_status;        /* Status of last wait operation, or */
  36.                     /*  semaphore count */
  37.     void    *msg;            /* Pointer to place to put mail, or */
  38.                     /*  to oldest queued mailbox message */
  39.     unsigned    *mail_size;        /* Pointer to place to put mail size */
  40.     };
  41.  
  42. #define MQE struct msg_queue_entry
  43.  
  44. MQE {
  45.     MQE        *next_msg;        /* Link to next message in mailbox */
  46.     unsigned    msg_size;        /* Size of this message */
  47.     char    *msg_text;        /* Pointer to message text */
  48.     };    
  49.  
  50. /*****************************************************************************
  51.  *                  Manifest Constants                 *
  52.  *****************************************************************************/
  53.  
  54. #define TIMER_PRIORITY        0xF000    /* Timer task is very high priority */
  55. #define STANDARD_PRIORITY    100    /* Priority of Joe Average task */
  56. #define STANDARD_STACK        2000    /* Stack size for Joe Average task */
  57.  
  58. enum { OKAY, TIMEOUT };            /* Wait return status values */
  59.  
  60. /*****************************************************************************
  61.  *                  Function Prototypes                 *
  62.  *****************************************************************************/
  63.  
  64. /*****************************************************************************
  65.  *                   start_RMAXTask()                     *
  66.  *****************************************************************************
  67.  * DESCRIPTION:    Initializes the RMAXTask software.  This function must be    *
  68.  *        called before any other RMAXTask functions are used.         *
  69.  *                                         *
  70.  * REVISIONS:     1 JUL 90 - RAC - Original definition.                 *
  71.  *****************************************************************************/
  72.  
  73. int start_RMAXTask(void);        /* 1 if all is well, 0 if error */
  74.  
  75. /*****************************************************************************
  76.  *                    stop_RMAXTask()                     *
  77.  *****************************************************************************
  78.  * DESCRIPTION:    Cleans up after the RMAXTask software.  Must be called         *
  79.  *        before the application returns to DOS.                 *
  80.  *                                         *
  81.  * REVISIONS:     1 JUL 90 - RAC - Original definition.                 *
  82.  *****************************************************************************/
  83.  
  84. void stop_RMAXTask(void);
  85.  
  86. /*****************************************************************************
  87.  *                 create_task()                     *
  88.  *****************************************************************************
  89.  * DESCRIPTION: Establishes a specified C function as an RMAXTask task and   *
  90.  *        makes it READY.                             *
  91.  *                                         *
  92.  * REVISIONS:     1 JUL 90 - RAC - Original definition.                 *
  93.  *        10 DEC 91 - RAC - Changed return value from simple error     *
  94.  *                   code to a pointer to the created task.    *
  95.  *****************************************************************************/
  96.  
  97. TDESC *create_task(            /* Pointer to task, or NULL if error */
  98.     char    *name,            /* Pointer to text name for task */
  99.     void    (*fn)(),        /* Ptr to the code for the task */
  100.     unsigned    priority,        /* Desired task priority */
  101.     unsigned    ssize            /* # of bytes for task's stack */
  102.     ); 
  103.  
  104. /*****************************************************************************
  105.  *                  kill_task()                     *
  106.  *****************************************************************************
  107.  * DESCRIPTION:    Allows one task to murder another.                 *
  108.  *                                         *
  109.  * NOTES:    This function must be used with extreme care to make sure    *
  110.  *        that the task being killed has his affairs in order.  He     *
  111.  *        should not "own" any dynamic memory, he should not have any  *
  112.  *        open files, etc.                         *
  113.  *                                         *
  114.  *        A task should NOT use this function to kill itself.  Tasks   *
  115.  *        wishing to commit suicide should do so by simply returning   *
  116.  *        from themselves, either by an explicit return or by simply   *
  117.  *        running off the end of themselves.  Tasks contemplating      *
  118.  *        suicide should also make sure their affairs are in order     *
  119.  *        as noted above.                             *
  120.  *                                         *
  121.  * REVISIONS:    10 DEC 91 - RAC - Adapted from auto_kill()             *
  122.  *****************************************************************************/
  123.  
  124. void kill_task(TDESC *victim);            /* Kill victim */
  125.  
  126. /*****************************************************************************
  127.  *                    yield()                     *
  128.  *****************************************************************************
  129.  * DESCRIPTION: Makes the calling task READY and then invokes the scheduler. *
  130.  *        If a task plans to run for a long time without either         *
  131.  *        waiting for an event or going to sleep, it should call this  *
  132.  *        routine periodically to allow higher-priority tasks the      *
  133.  *        chance to run.                             *
  134.  *                                         *
  135.  * REVISIONS:     1 JUL 90 - RAC - Original definition.                 *
  136.  *****************************************************************************/
  137.  
  138. void yield(void);
  139.  
  140. /*****************************************************************************
  141.  *                   suspend()                     *
  142.  *****************************************************************************
  143.  * DESCRIPTION: Suspends a task for a given period of time.  The time is     *
  144.  *        given in BIOS clock ticks, which occur at about 18.2 Hz.     *
  145.  *                                         *
  146.  * REVISIONS:     1 JUL 90 - RAC - Original definition.                 *
  147.  *****************************************************************************/
  148.  
  149. void suspend(
  150.     long    ticks            /* Sleep for <ticks> clock ticks */
  151.     );
  152.  
  153. /*****************************************************************************
  154.  *                   create_mailbox()                     *
  155.  *****************************************************************************
  156.  * DESCRIPTION: Creates a mailbox.                         *
  157.  *                                         *
  158.  * REVISIONS:     1 JUL 90 - RAC - Original definition.                 *
  159.  *****************************************************************************/
  160.  
  161. TDESC *create_mailbox(void);        /* Ptr to new mailbox, NULL if error */
  162.  
  163. /*****************************************************************************
  164.  *                  send_mail()                     *
  165.  *****************************************************************************
  166.  * DESCRIPTION: Sends a message to a mailbox.                     *
  167.  *                                         *
  168.  * REVISIONS:     1 JUL 90 - RAC - Original definition.                 *
  169.  *****************************************************************************/
  170.  
  171. int send_mail(                /* 1 if all is well, 0 if error */
  172.     void    *msg,            /* Pointer to message to